home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kparts / plugin.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  6.0 KB  |  178 lines
  1. /* This file is part of the KDE project
  2.    Copyright (C) 1999 Simon Hausmann <hausmann@kde.org>
  3.              (C) 1999 David Faure <faure@kde.org>
  4.  
  5.    This library is free software; you can redistribute it and/or
  6.    modify it under the terms of the GNU Library General Public
  7.    License as published by the Free Software Foundation; either
  8.    version 2 of the License, or (at your option) any later version.
  9.  
  10.    This library is distributed in the hope that it will be useful,
  11.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.    Library General Public License for more details.
  14.  
  15.    You should have received a copy of the GNU Library General Public License
  16.    along with this library; see the file COPYING.LIB.  If not, write to
  17.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.    Boston, MA 02110-1301, USA.
  19. */
  20. #ifndef PLUGIN_H
  21. #define PLUGIN_H
  22.  
  23. #include <qobject.h>
  24. #include <kaction.h>
  25. #include <kxmlguiclient.h>
  26.  
  27. class KInstance;
  28.  
  29. namespace KParts
  30. {
  31.  
  32. /**
  33.  * A plugin is the way to add actions to an existing KParts application,
  34.  * or to a Part.
  35.  *
  36.  * The XML of those plugins looks exactly like of the shell or parts,
  37.  * with one small difference: The document tag should have an additional
  38.  * attribute, named "library", and contain the name of the library implementing
  39.  * the plugin.
  40.  *
  41.  * If you want this plugin to be used by a part, you need to
  42.  * install the rc file under the directory
  43.  * "data" (KDEDIR/share/apps usually)+"/instancename/kpartplugins/"
  44.  * where instancename is the name of the part's instance.
  45.  *
  46.  * You should also install a "plugin info" .desktop file with the same name.
  47.  * \see PluginInfo
  48.  */
  49. class KPARTS_EXPORT Plugin : public QObject, virtual public KXMLGUIClient
  50. {
  51.     Q_OBJECT
  52. public:
  53.     /**
  54.      * Struct holding information about a plugin
  55.      */
  56.     struct PluginInfo
  57.     {
  58.         QString m_relXMLFileName; ///< relative filename, i.e. kpartplugins/name
  59.         QString m_absXMLFileName; ///< full path of most recent filename matching the relative filename
  60.         QDomDocument m_document;
  61.     };
  62.  
  63.     /**
  64.      * Construct a new KParts plugin.
  65.      */
  66.     Plugin( QObject* parent = 0, const char* name = 0 );
  67.     /**
  68.      * Destructor.
  69.      */
  70.     virtual ~Plugin();
  71.  
  72.     /**
  73.      * Reimplemented for internal reasons
  74.      */
  75.     virtual QString xmlFile() const;
  76.  
  77.     /**
  78.      * Reimplemented for internal reasons
  79.      */
  80.     virtual QString localXMLFile() const;
  81.  
  82.     /**
  83.      * Load the plugin libraries from the directories appropriate
  84.      * to @p instance and make the Plugin objects children of @p parent.
  85.      *
  86.      * It is recommended to use the last loadPlugins method instead,
  87.      * to support enabling and disabling of plugins.
  88.      */
  89.     static void loadPlugins( QObject *parent, const KInstance * instance );
  90.  
  91.     /**
  92.      * Load the plugin libraries specified by the list @p docs and make the
  93.      * Plugin objects children of @p parent .
  94.      *
  95.      * It is recommended to use the last loadPlugins method instead,
  96.      * to support enabling and disabling of plugins.
  97.      */
  98.     static void loadPlugins( QObject *parent, const QValueList<PluginInfo> &pluginInfos );
  99.  
  100.     /**
  101.      * Load the plugin libraries specified by the list @p pluginInfos, make the
  102.      * Plugin objects children of @p parent, and use the given @p instance.
  103.      *
  104.      * It is recommended to use the last loadPlugins method instead,
  105.      * to support enabling and disabling of plugins.
  106.      */
  107.     static void loadPlugins( QObject *parent, const QValueList<PluginInfo> &pluginInfos, const KInstance * instance );
  108.  
  109.     /**
  110.      * Load the plugin libraries for the given @p instance, make the
  111.      * Plugin objects children of @p parent, and insert the plugin as a child GUI client
  112.      * of @p parentGUIClient.
  113.      *
  114.      * This method uses the KConfig object of the given instance, to find out which
  115.      * plugins are enabled and which are disabled. What happens by default (i.e.
  116.      * for new plugins that are not in that config file) is controlled by
  117.      * @p enableNewPluginsByDefault. It can be overridden by the plugin if it
  118.      * sets the X-KDE-PluginInfo-EnabledByDefault key in the .desktop file
  119.      * (with the same name as the .rc file)
  120.      *
  121.      * If a disabled plugin is already loaded it will be removed from the GUI
  122.      * factory and deleted.
  123.      *
  124.      * This method is automatically called by KParts::Plugin and by KParts::MainWindow.
  125.      *
  126.      * If you call this method in an already constructed GUI (like when the user
  127.      * has changed which plugins are enabled) you need to add the new plugins to
  128.      * the KXMLGUIFactory:
  129.      * \code
  130.      * if( factory() )
  131.      * {
  132.      *   QPtrList<KParts::Plugin> plugins = KParts::Plugin::pluginObjects( this );
  133.      *   QPtrListIterator<KParts::Plugin> it( plugins );
  134.      *   KParts::Plugin * plugin;
  135.      *   while( ( plugin = it.current() ) != 0 )
  136.      *   {
  137.      *     ++it;
  138.      *     factory()->addClient(  plugin );
  139.      *   }
  140.      * }
  141.      * \endcode
  142.      */
  143.     static void loadPlugins( QObject *parent, KXMLGUIClient* parentGUIClient, KInstance* instance, bool enableNewPluginsByDefault = true );
  144.  
  145.     /**
  146.      * Returns a list of plugin objects loaded for @p parent. This
  147.      * functions basically calls the queryList method of
  148.      * QObject to retrieve the list of child objects inheriting
  149.      * KParts::Plugin .
  150.      **/
  151.     static QPtrList<Plugin> pluginObjects( QObject *parent );
  152.  
  153. protected:
  154.     /**
  155.      * Look for plugins in the @p instance's "data" directory (+"/kpartplugins")
  156.      *
  157.      * @return A list of QDomDocument s, containing the parsed xml documents returned by plugins.
  158.      */
  159.     static QValueList<Plugin::PluginInfo> pluginInfos( const KInstance * instance );
  160.  
  161.     /**
  162.      * @internal
  163.      * @return The plugin created from the library @p libname
  164.      */
  165.     static Plugin* loadPlugin( QObject * parent, const char* libname );
  166.  
  167.     virtual void setInstance( KInstance *instance );
  168.  
  169. private:
  170.     static bool hasPlugin( QObject* parent, const QString& library );
  171.     class PluginPrivate;
  172.     PluginPrivate *d;
  173. };
  174.  
  175. }
  176.  
  177. #endif
  178.